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NAME 

ALN, doindex - GEMDOS linker and archive index builder 


SYNOP S I 23 
aln [ _option_ ] ... 

{ _file_ | [ -x _file_ ] j ( -i _file_label_ ] } 

doindex [ -i ] [ -w ] _file_ 


EXAMPLE 

[in a batch file or from a command shell] 

aln -o test -s -m gemstart test gemlib libf 

This is a typical link for a program compiled with the C 
compiler: the startup file gemstart.o is linked first, followed 

by the object module produced by the compiler (test.o), plus the 
C runtime library gemlib and the floating-point library libf. 
This example produces an executable called test.prg (because of 
the -o flag), includes global symbols in that executable (the -s 
flag), and produces a load map on the standard output (the -m 
flag) . 


DESCRIPTION 

_File_ arguments are either object modules or archives of object 
modules (created with ar68). If _file_ has no extension (e.g. 
’.o'), ALN looks for both _file_ and _file_.o. All _options_ must 
be specified before the first -x, -i, or _file_ argument. 


If no arguments are present on the command line, (i.e. ALN was 
double-clicked from the GEM desktop) ALN will display its version 
number and prompt for switches and filenames. More than one 
switch or filename may be entered per line, and a blank line ends 
the input and begins the link. After the link ALN will wait for 
the user to press the return key before returning to the desktop 
(just like the -d flag). 
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Ttie _opt ions_ are : 


-a _text_ _data_ _bss_ 

Absolute link: _text,_ _data,_ and _bss_ are indicators for 
each of those segments: a (hexadecimal) address, the letter 
'r', or the letter 'x'. See the section on absolute 
linking, below. 

-d 

Desktop: wait for the "Return" key after the link before 

terminating. This gives the user time to read any error 
messages before returning to the desktop. Note that if you 
start ALN with no arguments, -d is implied. 

-f 

File symbols: when specified, ALN will generate symbols of 
type "file" for each object module processed, and symbols of 
type "archive file" (bits 6 and 7 in the type field set) for 
each archive processed. These symbols cause sid to fail, but 
they can be understood by Atari's [unreleased] debugger, db. 
This flag sets the -s flag, unless -1 is used also. See 
FILE SYMBOLS , below. 

-1 

Local symbols: like -s, but includes local symbols as well 
as globals in the output file. 


Map: produces a load map on standard output. The load map 
contains each symbol's name, value, and type. The load map 
lists only global symbols unless -1 is used. The symbol 
types are encoded as follows: 


C: 

Common 

F: 

File 

G: 

Global 

A: 

Archive (only with "File") 

E: 

External 

Q: 

eQuated 

L: 

Local 

R: 

Register 


-o _file_ 

Output: produce output on _file_. If _file_ has an 

extension (e.g. '.prg'), that extension is used. 

Otherwise, a default extension is appended to _file_: '.prg' 
for a normal link, '.o' for a partial link (when -p is 
specified), and '.abs' for an absolute link (when -a is 
specified). 

If -o is not specified, the output file name is taken from 
the first linked file on the command line (including 
archives specified with -x and data files specified with 
i), plus the appropriate extension. Note that if this would 
make the output file name the same as the first input file 
(e.g. "aln -p al.o a2.o" which would use "al.o" as the 
output file name), ALN will abort: in this case, -o must be 
specified. 
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-P 


Partial link: collect the named object modules and libraries 
into a single object module, suitable for later passes 
through ALN. 

-s 

Symbols: generate a symbol table in the output file 
including all global symbols. (Use -1 (only) to get both 
locals and globals.) 

-u 


Unresolved: do not abort the link upon encountering 
unresolved externals. The unresolved symbols are listed on 
the standard output, but the link proceeds as if their 
values were zero. 


-v 


Verbose: causes ALN to print a banner line at the start of 
the link and memory usage statistics at the end. If the -v 
flag is present twice, the name of each file (module or 
archive) is printed as it is linked. If this flag appears 
three times, ALN also prints the name of each module it 
links from within each archive. 


-w 


Warnings: give warnings on standard output about multiply- 
defined globals. See the section DUPLICATE SYMBOLS IN 
MODULES for more information. 
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After the options on the command line, the following arguments 
are recognized in addition to file arguments: 

-i _file_ _label_ 

Include file: _file_ will be included in the data segment 
verbatim. The global, data-segment symbol _label_ is created 
and gets the starting address of _file_ as its value? the 
global symbol _labelx_ gets its ending address. That is, 
the ending label is the same as the starting label with the 
letter 'x' appended. If _label_ is eight or more characters 
long, it is truncated to seven characters before appending 
the letter 'x' (so "longname" becomes "longnamx"). 

-x _file_ 

All modules: include all modules from archive _file_. 

Note that with the -x option, the modules are linked in the 
order they appear in the archive, so for multiply-defined 
global symbols, the first occurrence is the one which 
prevails. This is the opposite behavior from the regular 
linking process. 


The 'command-file' switch can appear anywhere: 

-c _file_ 

Command file: _file_ is read in as though its contents had 
appeared on the command line in place of the -c switch. All 
command-line switches may be used (but, again, no _options_ 
may occur after the first -i, -x, or _file_ argument in 

either the command line or the -c file). Arguments in 
_file_ may be delimited by white space (tabs, spaces, and 
newlines) or commas. 
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DOXNDEX - ARCHIVES AND THEIR INDEXE 


ALN requires that an index file exist for each archive included 
in a link. This index file has the same name as the archive, 
with the extension '.ndx', and should be in the same disk 
directory as the archive itself. If ALN can not find an index 
file for an archive you name, it will produce an error message to 
that effect and abort. 

Doindex builds an index file for the named archive (regardless of 
whether one already exists). If desired, doindex will also print 
a human-readable index of the archive on the terminal (that is, 
on standard output), and inform you of symbols which are declared 
global in more than one module in the archive. The last such 
declaration is the one which will prevail when that archive is 
used in the linking process. 

The arguments to doindex are as follows: 

-i 

Index: print an index of the archive to the standard output, 
including the name of each module, the global symbols it 
exports, and the external symbols it imports. Finally, list 
the symbols which are external to the archive (imported by 
modules in the archive but not exported by any of them). 

-w 


Warnings: produce warnings about duplicate symbols in the 
archive. 

The last argument to doindex is the name of an archive. Doindex 
opens that archive, builds its index file, and writes that file 
to _file_.ndx in the same disk directory as _file_ itself. 

The index file contains dependency information so the linker does 
not have to go through the whole archive to resolve all the 
symbols. It consists of information about each module in the 
archive, the name of each symbol exported by any module in the 
archive and the module which exports it, and a dependency list 
for each module, stating, "if you need module A, you will also 
need modules B, C, and D." During linking, this information is 
collected together for each symbol which is unresolved at the 
time the archive appears in the command line, and only the needed 
modules are read in from the archive. 
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ABSOLUTE LI 1ST PC I INTO 

An absolute link is one for which the -a flag is specified. 

Note that the -a flag takes three arguments: the base indicator 
for the text, data, and BSS segments, respectively. 

A base indicator can be one of the following: 

A) a hexadecimal value, which is taken as the starting 
address of the segment. 

B) the letter 'r', which stands for "relocatable." 

C) the letter 'x', which stands for "contiguous with the 
previous segment" (whether that segment is absolute or 
relocatable). 

During an absolute link, an absolute object module is produced, 
which includes the base address of each segment in its header. 
See the section on FILE FORMATS for more details. 

In an absolute object module, all references to an absolute 
segment have already been resolved; that is, there is no 
relocation information for them, because they are not 
relocatable. References to relocatable segments still have 
relocation information associated with them. If there are no 
references to relocatable segments (either because there are no 
such segments, or no references to them), the relocation 
information is missing entirely, and a flag in the header 
indicates this. 

For example, when linking a program to be placed in ROM, ALN 
might be used to link with the text and data segments contiguous, 
starting at the address of the ROM (say, hex FFOOOO), and with 
the BSS segment at some address in RAM (say, hex 4000). This can 
be done with ALN as follows: 

aln -o rom.abs -a ffOOOO x 4000 romfile.o 

Alternatively, a program with its data segment in ROM, but with 
relocatable text and BSS segments, could be linked as follows: 

aln -o romdata.abs -a r ffOOOO r romfile.o 

Of course, it would be up to the program loader to perform the 
text and BSS relocation at execute time. 
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FILE SYMBOLS 

ALN will generate file symbols when the -f flag is used. A file 
symbol appears at the start of each object module in the symbol 
table. Its name is the name of the module, its value is the 
start of the text segment of that module, and its type is TEXT 
FILE (that is, hex 0280). With these symbols, you can determine 
which object module a given symbol came from, because the symbols 
from a module immediately follow its file symbol. 

ALN also generates a file symbol at the start of each archive: 
this is a special symbol in that its name is the name of the 
archive, but its type is TEXT FILE ARCHIVE (hex 02C0). 
Furthermore, a second symbol is generated at the end of the 
archive: it has the same type, but its name is blank. This 
signals the end of the previous archive. 

The use of bit 6 of the type field to mean "archive" is an 
extension to the Alcyon symbol-table standard. As such, existing 
tools like sid and nm68 can not be expected to understand it, but 
Atari's [unreleased] debugger db does. (It happens that sid does 
not understand file symbols at all, let alone archive-file 
symbols, so the -f option should not be used if sid will be used 
to debug the output.) 


FILE FORMATS 

The files ALN deals with all have the same basic format (except 
archives; see below): 

Header 

Text 

Data 

Symbol Table 
Relocation Information 

The header includes information such as the sizes of the other 
segments and the type of the file (encoded in a "magic number"). 
Any segment may be empty or missing except the header. 
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OBJECT MODULES 

A standard (relocatable) object module header has the 
following format: 

struct oheader { 


int magic; 

/* 

the magic number 0x601a * 

/ 

long 

tsize; 

/* 

text segment size */ 


long 

dsize ? 

/* 

data segment size */ 


long 

bsize; 

/* 

bss segment size */ 


long 

ssize; 

/* 

size of the symbol table 

*/ 

char 

reserved[10]; 

/* 

ten unused bytes (must be 

zero) 


Following the header is the text segment of the module (tsize 
bytes long), then the data segment (dsize bytes long). Following 
that is the symbol table, and then the fixup information for the 
module. Each word of the fixup information describes one word of 
the text or data segment. 


EXECUTABLE PROGRAM EXLES 


Executable programs (.PRG files) have almost the same format as 
relocatable object modules. The header is the same, and the text 
and data segments, plus the symbol table, follow. The relocation 
information is different, though; it consists of a longword 
telling the byte offset to the first longword needing a fixup, 
then a series of bytes with the offset to the next longword 
needing a fixup. A zero terminates this list. If there are no 
fixups to be done, the initial-offset longword is zero. The 
byte-offsets take these special values: 


Value 


Meaning 


0 

1 

2.. 254 (even) 

3.. 255 (odd) 


End of fixup list. 

Skip 254 bytes and keep going, 
skip that many bytes and fix up. 
undefined. 


Version 1.01 


7/6/87 A 


Pratt 



ALN (Atari Linker) 


Atari Corporation 


Page 11 


-A. 33 SOLUTE OBJECT MODULE S 


An absolute object module header has the following format: 


struct abshdr { 



int magic; 

/* 

the magic number 0x601B */ 

long tsize; 

/* 

text segment size */ 

long dsize; 

/* 

data segment size */ 

long bsize; 

/* 

bss segment size */ 

long ssize; 

/* 

size of the symbol table */ 

long reserved; 

/* 

an unused longword */ 

long textbase; 

/* 

the base of the text segment */ 

int relocflag; 

/* 

zero if reloc info exists */ 

long database; 

/* 

the base of the data segment */ 

long bssbase; 

/* 

the base of the bss segment */ 


If there is any relocation information, the relocflag field in 
the header will be zero, and that information will follow the 
symbol table (if any). If the relocflag field is not zero (and 
in particular if it is minus one), there is no relocation 
information. This is always the case when none of the three 
segments is relocatable, but it can also happen if there are no 
references to a relocatable segment (e.g. the text segment is 
relocatable, but contains position- independent code, and the 
data and BSS segments are absolute). 


ARCHIVES 

Archives are files containing other files, usually relocatable 
object modules. The "header" of an archive file is simply the 
magic number FF65 (hex). The archived files consist of a header, 
then the file itself. The next file follows immediately. A zero 
word follows the last file in the archive. The archived-file 
header is as follows: 

struct arheader { 

char a_fname[14]; 
long a_modti; 
char a_userid; 
char a_gid; 
int a_fimode? 
long a_fsize; 
int reserved; 


The file, a_fsize bytes 


/* the file name */ 

/* the last-modified time */ 

/* not used in TOS */ 

/* not used in TOS */ 

/* the file's mode word */ 

/* the file's size in bytes */ 
/* zero */ 


’ worth, immediately follows the header. 
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NOTES 


DUPLICATE SYMBOLS IIS f MODULES 

When the same symbol is exported (declared as global) from 
multiple object modules, the symbol value exported from the first 
such module will take precedence. When the same symbol is 
exported by multiple modules in one archive, the last such module 
will take precedence (this is taken care of by doindex when it 
builds the index). Therefore, in the case of two archives 
exporting the same symbol (from modules exporting needed 
symbols), the last definition in the first archive is the one 
which will be used. 

However, if an archive is included with -x, the modules are read 
in archive order, and the first instance of a symbol is the one 
which prevails. 

Unless the -w flag is used, you will get no notification that 
multiple files exported the same symbol. 


UNUSED MODULES UNT LIBRARIE S 

Since the dependency information is built from the archive, 
certain conditions can cause it to be out-of-date with respect to 
a given link. 

For example, if archive Z contains modules M and N, and M depends 
on N because it needs symbol S, the index file for Z will reflect 
this. But if the symbol S is exported by a file Y earlier in a 
particular link, then module N is not actually needed at all. 

ALN will read module N from the archive, but will then notice 
that both N and Y are exporting symbol S. This will produce a 
warning message if -w is specified. Finally, since Y occurs 
earlier in the link than N, the value of symbol S is taken from 
Y. ALN will notice that module N is not in fact used in the 
linking process, and will discard N completely, with another 
warning message. 
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EXAMP L.ES 


(1) 

aln -o 

apskel apstart.o 

(2) 

aln -s 

-o myfile.prg -u 

(3) 

aln -s 

-c foo.aln tl t2 

(4) 

aln -s 

-o myfile.prg -c 


apskel.o gemlib aesbind vdibind 
tl t2 gemlib 
gemlib 
foo.aln 


Example (1) 
Example (2) 


Example (3) 


Example (4) 


links the GEM application apskel.o for execution. 

links tl.o and t2.o together, along with the 
library gemlib, to produce myfile.prg, with 
symbols. 

sets the -s flag, then reads foo.aln for more 
command-line options, and then specifies that tl 
and t2 are files to be linked. If "foo.aln” 
contains "-o myfile.prg -u" then this is identical 
to example (2). 

sets -s and sets the output file to "myfile.prg," 
then reads foo.aln for more options. This time, 
if "foo.aln" contains "-u tl t2 gemlib" then this 
is identical to examples (2) and (3). 
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ALIM FOR. LINKS 8 USERS 

ALN performs the same function as link68 plus relmod. If you 
have batch files which invoke link68, you can change them to use 
ALN by doing the following: 

1. Change bracketed options (like [u,s]) into the corresponding 
ALN options (-u -s). 

2. Change the assignment statement 

"output.68k=inputl,input2,..." into something like "-o 
output.prg inputl input2 ..." 

3. Change the command-file option (like [co[myfile.inp]]) into 
the corresponding ALN option "-c myfile.inp" 

4. Do the same things in any command files (like myfile.inp). 
Note that you don't have to remove the commas from your 
command files; ALN will accept commas as separators in 
command files (but not from the command line). 

For example, if you usually use the command lines: 

link68 [s,u] myfile.68k=C:gemstart,myfile,C:gemlib 
relmod myfile.68k myfile.prg 
rm myfile.68k 

you should change that to: 

aln -s -u -o myfile.prg C:gemstart myfile C:gemlib 

(From now on it will be assumed that you get rid of the relmod 
and rm commands, since ALN generates ".prg" files directly.) 

If you currently use a link68 input file, and your command line 
is like this: 

link68 [s,u r co[myfile.inp]] 
and the file "myfile.inp" contains a line like this: 

myfile.68k=C:gemstart f myfile , C:gemlib 
you should change that to: 

aln -u -s -c myfile.inp 
and "myfile.inp" should contain: 

-o myfile.prg C:gemstart myfile C:gemlib 
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ERROR. MESSAGES 

Most of the common error messages from ALN are self-explanatory; 
for instance, "File <x> is not an archive." In some cases, 
however, a little more explanation is in order. 

Some errors refer to a 16-bit fixup overflow. This means that in 
resolving an external reference in the file, a value greater than 
32K-1 or less than -32K had to be put in a single word. This can 
happen if you have a PC-relative reference to a symbol more than 
32K away. This is only a warning, since you might be using the 
value as an unsigned integer (in which case it might not be an 
overflow). 

Other errors report that they occurred at a given offset (always 
hex) in a given module. The offset is always in bytes, counting 
from the beginning of the text segment of that module. 


RELEASE NOTES 

This manual accompanies ALN version 1.01. This linker has been 
used internally at Atari for some time, and is believed to be 
robust and complete. If you encounter any unexpected behavior, 
or have any other comments about it, please contact us at Atari, 
at this address: 

Atari Corporation 
Attn: Allan Pratt (ALN) 

1196 Borregas Avenue 
P.O. Box 3427 
Sunnyvale, CA 94088-3427 

Additionally, the author can be reached electronically at 
atarilapratt (on USENET) and as "apratt" on GENIE. Also, Atari 
Corp. is online on BIX and CompuServe. 
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